Pyth Examples Contribution

Type of Contribution

• New Example Project (Adding a new example to demonstrate Pyth integration)
• Bug Fix (Fixing an issue in existing examples)
• Documentation Update (Improving README, comments, or guides)
• Enhancement (Improving existing functionality or adding features)
• Hackathon Submission (Submitting a project from a hackathon)

Project Information

Project/Example Name: Param Protocol: Hybrid "Base + Bonus" Reward Model

Pyth Product Used:

• Pyth Price Feeds
• Pyth Entropy
• Multiple Products
• Other: ________

Blockchain/Platform:

• Ethereum/EVM
• Solana
• Aptos
• Sui
• Fuel
• Starknet
• TON
• Other: ________

Description

What does this contribution do?

This PR adds a new example project, ParamProtocol, which demonstrates an innovative incentive model for a data monetization platform.

The contribution consists of a single ParamProtocol.sol file which conveniently includes:

1. The main ParamProtocol contract (an ERC721 + Pyth Entropy consumer).
2. A MockPTK contract (an ERC20 + AccessControl) for easy deployment and testing of the reward token.

How does it integrate with Pyth?

This contract uses Pyth Entropy to power a probabilistic bonus reward system.

1. It implements the IEntropyConsumer interface.
2. The main mintDataNFT function is payable. When called, it uses pyth.getFeeV2() to get the current fee and then calls pyth.requestV2{value: msg.value}() to request a random number.
3. The contract securely implements the entropyCallback function, which receives the randomNumber from the Pyth network.
4. This randomNumber is then used in a _calculateBonusReward function to determine a tiered, probabilistic bonus (Common, Rare, or Legendary), which is then minted to the user.

What problem does it solve or demonstrate?

This project demonstrates an innovative solution to the user incentive problem for data contribution platforms.

• The Problem: Fixed rewards are predictable but boring. Pure lotteries are exciting but risky, as a user's contribution might yield no reward, which feels unfair.
• The "Base + Bonus" Solution: This contract implements a hybrid incentive model that provides the best of both worlds:
  1. Instant Base Reward: Users instantly receive a guaranteed "base reward" (10 PTK) for their contribution, ensuring they always get value.
  2. Asynchronous Bonus Reward: The same transaction also triggers a request to Pyth Entropy. 1-2 minutes later, the user receives a separate, probabilistic "bonus reward."

This creates a system that is both trustworthy (guaranteed value) and exciting (a provably-fair chance at a jackpot), all powered by Pyth.

Directory Structure (for new examples)

entropy/param-protocol/
├── ParamProtocol.sol    # Unified contract file (includes MockPTK)
└── README.md            # Project documentation

Testing & Verification

How to Test This Contribution

These instructions are for testing on Base Sepolia using Remix IDE.

Prerequisites

• A browser with [MetaMask](https://metamask.io/) installed.
• Some Base Sepolia ETH for gas (from a faucet).

Setup & Run Instructions

# 1. Open the ParamProtocol.sol file in Remix.
# 2. Compile the file (e.g., with compiler 0.8.20).
# 3. Change Remix Environment to "Injected Provider - MetaMask" and connect to Base Sepolia.

# 4. Deploy `MockPTK`
#    - Select `MockPTK` from the contract dropdown and deploy it.
#    - Copy the deployed MockPTK address.

# 5. Deploy `ParamProtocol`
#    - Select `ParamProtocol` from the contract dropdown.
#    - In the deploy fields:
#      - _ptkTokenAddress: [Paste MockPTK Address from step 4]
#      - _pythAddress: 0x41c9e39574F40Ad34c79f1C99B66A45eFB830d4c (Base Sepolia Entropy)
#    - Deploy the contract.
#    - Copy the deployed ParamProtocol address.

# 6. Grant Minting Permission
#    - In Remix, go to your deployed `MockPTK` contract.
#    - Call the `grantRole` function:
#      - role: 0x9f2df0fed2c77648de5860a4cc508cd0818c85b8b8a1ab4ceeef8d981c8956a6
#      - account: [Paste ParamProtocol Address from step 5]

# 7. Test the Full Flow
#    - Go to your deployed `ParamProtocol` contract.
#    - Call `getPythFee()` to get the current fee (e.g., 15000000000001).
#    - Paste this fee into the `VALUE` field at the top of the Remix panel (set to Wei).
#    - Call `mintDataNFT` with any CID string (e.g., "my-data-cid") and a contributor address.
#    - Transaction will succeed.

# 8. Verify the Results
#    - Instantly: Call `getPtkBalance(contributor_address)`. It will return 10000000000000000000 (10 PTK).
#    - Wait 1-2 minutes: Call `getPtkBalance(contributor_address)` again.
#    - The balance will have increased by the bonus amount (e.g., 15 PTK, 60 PTK, or 1010 PTK).

Deployment Information (if applicable)

Network: Base Sepolia

Contract Address(es):

Added in the README

Demo URL: ON ETHONLINE project page

Checklist

Code Quality

• Code follows existing patterns in the repository
• Proper error handling implemented
• No hardcoded values (use environment variables where appropriate)

Testing

• Tested locally and works as expected
• All existing functionality still works (no breaking changes)

Additional Context

Related Issues

Fixes #### Screenshots/Demo (if applicable)

Notes for Reviewers

This is a submission for the ETHGlobal Hackathon Pyth Entropy prize. The core innovation is the "Base + Bonus" hybrid incentive model, which we believe is a strong, real-world use case for Pyth Entropy.

The ParamProtocol.sol file was intentionally designed to include the MockPTK token for simple, one-file testing in Remix.

Thank you for reviewing!